feat(runtime): fill MicroVMRuntime lifecycle methods (RIG-2493) - #719
Merged
mattwilkinsonn merged 3 commits intoAug 30, 2026
Merged
Conversation
This was referenced Aug 28, 2026
|
Compass engineering docs preview: https://compass-runner-rig-2493-u4-m.compass-eng-docs.pages.dev Deployed from |
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-u4-microvm-lifecycle
branch
2 times, most recently
from
August 28, 2026 07:15
c4480be to
56eed91
Compare
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-u3-host-exec
branch
from
August 28, 2026 10:09
869399a to
81856f8
Compare
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-u4-microvm-lifecycle
branch
from
August 28, 2026 10:11
56eed91 to
b95a89a
Compare
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-u3-host-exec
branch
from
August 28, 2026 11:09
81856f8 to
417292b
Compare
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-u4-microvm-lifecycle
branch
from
August 28, 2026 11:11
b95a89a to
9f07047
Compare
…rvisor (RIG-2493) U2 of the frozen microVM Runner V2b plan (`docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md`, §Plan U2 / §(b)). Replaces the V2a `healthService` (which U1 left embedding `UnimplementedGuestControlHandler` to satisfy the widened interface) with the full `supervisor` implementing every `GuestControl` RPC. ### What - **State gate** (`booting → ready → provisioned`, mutex-guarded): `Exec`/`ExecStream` refuse with `FailedPrecondition` until `Provision` opens the gate. - **`Provision`** records `default_exec_uid` (validated non-zero) + `base_env`; a non-empty `nft_script` answers `Unimplemented` (V3's); a second call or a not-ready guest answers `FailedPrecondition`. - **`Exec`** (one-shot): uid resolve (absent → session default, `0` → refused), env merge (exec keys win), stdin via `bytes.Reader` never argv, 8 MiB-capped stdout/stderr buffers (`ResourceExhausted` on overflow — the acknowledged divergence from the podman contract, OQ-E), guest-side timeout, non-zero exit is a **successful** `ExecResponse`, ctx-cancel → SIGKILL + reap. - **`ExecStream`** (bidi): first frame must be `StartExec`; `ExecStarted` is emitted first; a shared send-mutex serializes the demuxed `stdout`/`stderr`/`ExecExit` down-frames; stdin frames + `StdinClose` half-close the child; a broken stream or ctx-cancel → SIGKILL + reap; the terminal `ExecExit` always comes from our own reap. - **`Signal`**: `exec_id` → process-group signal; unknown/exited exec → no-op success; empty `exec_id` → `initiateStop` (the §(d) guest-stop path). - **Stop → power-off**: `run()` derives a serving ctx wired to `stopServing`; after serve returns, an RPC-triggered stop with no serve error calls `powerOff()` (`syscall.Reboot(LINUX_REBOOT_CMD_POWER_OFF)`), the PID-1-legal shutdown. The Unix-signal path (`cmd/compass-guestd` `signal.NotifyContext`) is a **distinct** trigger and returns as before, per §(d). - **Peer-CID guard**: `peerCIDListener` refuses any non-host CID before the first HTTP byte (hermetic non-vsock listeners are allowed); the handler carries `WithReadMaxBytes(16 MiB)` (OQ-E). - **Boot nonce**: `cmdline.go` parses `compass.boot_nonce=<hex>` (absent → nil, empty/non-hex → error); the supervisor echoes it on `HealthResponse.boot_nonce` (U1's additive field) so Start binds the guest to the VM it launched (§(e)). Boot steps 1–4 are byte-identical; only the serve step is retyped to `*supervisor` and gains the `powerOff` seam. ### Verification `go build ./...` clean (whole module); `go test ./internal/guestd/...` ok; `go test -race ./internal/guestd/...` ok; `gofmt -l internal/guestd/` clean. The hermetic suite (`supervisor_test.go`) drives an in-memory h2c listener with real host child processes and covers every §(b) acceptance row (gate refusal, uid-0 refusal, default-uid resolution, stdin-not-argv, env merge, non-zero-exit success, stream demux ordering, signal-kills-live-child, signal-on-exited no-op, broken-stream reap, peer-CID pure function, RPC-stop → power-off). ### Guest PATH resolution (CI fix, folded) `buildChild` spawned via `exec.Command(argv[0], …)`, whose bare-name resolution runs `LookPath` against guestd's OWN process environment — and guestd is PID 1 with no `PATH`, so a bare `argv[0]` (`echo`, `sh`, and in production `compass-agent`) never resolved: the first live KVM boot failed the exec rows with `executable file not found in $PATH`. The hermetic suite false-greened because it runs in-process with the test's ambient `PATH`. Fix (the container-baked-PATH analog, §(b)): `mergeEnv` floors a default `PATH=/bin:/usr/bin:/sbin:/usr/sbin` when neither the session base env nor the exec env supplies one, and `buildChild` resolves `argv[0]` against that merged `PATH` (via `resolveProgram`, honoring the session env, not the process env) — a name with a slash is used as-is, so absolute-path execs are unchanged. Regression: `TestExecResolvesBareCommandViaSessionPATH` (a base_env PATH pointing at a probe absent from the process PATH; fails before the fix) and `TestMergeEnvFloorsDefaultPATH`. Ledger-impact: none Spec-impact: none. Refs RIG-2493 Co-authored-by: Matt Wilkinson <matt@rigel.build>
… (RIG-2493)
U3 + U3b of the frozen microVM Runner V2b plan (`docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md`, §Plan U3/U3b, §(c)/§(e)). The host-side client half of the exec control plane: a `GuestExec` layer over U1's generated `GuestControl` client, plus the backend-portable error type the runner's kill-classifier keys on.
### U3b — portable exit-signal error (`internal/runtime/exit_status_error.go`, new)
`ExitStatusError{Code int; Signal syscall.Signal}` with `Error()`, in package `runtime`. A remote guest exec cannot forge an `*exec.ExitError`, so the microVM `waitFunc` constructs this instead for a signalled guest exit. `internal/runner/agent_exec.go`'s `isDeliberateKill` is widened to `errors.As` on `*runtime.ExitStatusError` **first** (a non-zero signal ⇒ deliberate kill), then the existing `*exec.ExitError` SIGKILL branch **unchanged** — so the podman byte-path is byte-identical and only the microVM backend gets the new classification.
### U3 — GuestExec layer (`internal/runtime/microvm/exec.go`, new)
Plain structs (`ExecCall`/`ExecResult`/`StreamCall`/`ExitStatus`) mirror the proto so `runtime` types don't leak into `microvm` (`microvm` must not import `runtime`; U4 makes `runtime` import `microvm`).
- **`Exec`** (one-shot RPC): a non-zero exit is a successful `ExecResult`; a refusal/transport failure is an error; a host-side timeout → `*microvm.TimeoutError`.
- **`ExecStream`** (bidi): opens the stream, sends `StartExec`, **awaits `ExecStarted`** before returning; per-exec goroutines pump the `Stdin` pipe → stdin frames (`Close` → `stdin_close` + `CloseRequest`) and demux `stdout`/`stderr` response frames onto `io.Pipe` read ends, closing them on `ExecExit`.
- **`GuestStream.Kill`** issues a `Signal` RPC bounded by `killSignalTimeout` (never blocks teardown past it); **`Wait`** blocks on the demux goroutine and returns `ExitStatus{Code,Signal}`. A ctx-cancel stream break reports SIGKILL — guestd reaps the child bound to the broken stream.
### `podman.go` — funcs-backed ChildHandle
Adds unexported `newChildHandleFuncs(kill, wait func() error) *ChildHandle` plus `killFunc`/`waitFunc` fields. `Kill`/`Wait`/`Terminate` branch to the funcs path when `killFunc != nil`, else drive the original `cmd`/`cancel` path **untouched** (podman byte-unchanged). `Terminate` = kill then wait, returning the wait error (the exit status) when non-nil else the kill error — so a crash-vs-teardown consumer gets the exit signal.
### Verification
`go build ./internal/runtime/... ./internal/runner/...` clean; `go vet` clean over `runtime`, `runtime/microvm`, `runner`. Tests (all hardware-independent, no `microvm` build tag, no KVM):
- `exec_test.go` — fake `GuestControl` server on a unix listener over h2c Connect, dialed by a real client: one-shot non-zero exit is success + spec mapping; refusal is an error; one-shot timeout → `*TimeoutError`; stream demux ordering (interleaved frames land on the correct pipes, drained concurrently); stdin framing + `Close` → `stdin_close`; `Kill` issues the `Signal` RPC and `Wait` unblocks on the signalled exit; ctx-cancel breaks the stream and `Wait` reports SIGKILL.
- `child_handle_test.go` — `newChildHandleFuncs`: `Kill` invokes/propagates; `Wait` surfaces `*ExitStatusError` unchanged; `Terminate` return-value precedence.
- `deliberate_kill_test.go` — `isDeliberateKill` accepts a real `*exec.ExitError` from a SIGKILLed local child (podman-path regression guard) and `*runtime.ExitStatusError{Signal: SIGKILL}`, rejects a non-signal `ExitStatusError`, an unrelated error, and nil.
Ledger-impact: none
Spec-impact: none. Refs RIG-2493
Co-authored-by: Matt Wilkinson <matt@rigel.build>
U4 of the frozen microVM Runner V2b plan (docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md, Plan U4 / (c)/(d)/(e)). Fills the eight typed-error MicroVMRuntime stubs behind their frozen ContainerRuntime signatures against the V2a boot harness + the U3 GuestExec layer.
### Socket-path budget (CI fix, folded)
`e2eConfig` built its runroot with `t.TempDir()`, whose path embeds the test-function name. Under the 39-char `TestMicroVMExecStreamingKillSignalsExit` the widest per-session socket path — `<RunRoot>/microvm/<32-hex id>/virtiofsd.sock`, a 56-byte tail — reached 114 bytes, over the 107-byte Linux AF_UNIX `sun_path` cap, so virtiofsd's `bind(2)` failed EINVAL, the socket never appeared, and the boot timed out (`… did not appear within 10s`). `TestMicroVMLifecycleEndToEnd` (28-char name, 103 bytes) fit and booted. Production runroots are short and startup-budget-checked (`run.go` validateRuntimeDir); this is a pure harness artifact. Fix: `e2eConfig` uses a short `os.MkdirTemp("", "cvm")` runroot (cleaned via `t.Cleanup`), keeping the worst-case path well under the cap.
Refs RIG-2493
Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-u3-host-exec
branch
from
August 29, 2026 19:35
417292b to
3c87d57
Compare
rigel-mintaka
force-pushed
the
compass-runner/rig-2493-u4-microvm-lifecycle
branch
from
August 29, 2026 19:37
9f07047 to
1975856
Compare
mattwilkinsonn
approved these changes
Aug 30, 2026
mattwilkinsonn
deleted the
compass-runner/rig-2493-u4-microvm-lifecycle
branch
August 30, 2026 04:16
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is part of a stack containing 4 PRs:
mainU4 of the frozen microVM Runner V2b plan (docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md, Plan U4 / (c)/(d)/(e)). Fills the eight typed-error MicroVMRuntime stubs behind their frozen ContainerRuntime signatures against the V2a boot harness + the U3 GuestExec layer.
Refs RIG-2493
Co-authored-by: Matt Wilkinson matt@rigel.build